DefaultCredentialProvider Credential Options

Configuration-driven Azure Identity options, including subprocess timeouts and token-acquisition retries

The DefaultCredentialProvider builds a ChainedTokenCredential whose links depend on the hosting environment. Every link is created from an Azure Identity options object, and those options are configurable from IConfiguration through an optional Credential subsection.

In particular, this makes subprocess timeouts, tenant scoping, HTTP retry options and diagnostics reachable without abandoning the provider and constructing credentials by hand.

DefaultCredentialProvider is part of Diginsight.Components.Configuration.

The configuration surface is entirely additive: when the Credential section is absent, the provider produces exactly the credentials it produced before the section existed.

Table of Contents

• 📋 Overview
  • Key Features
  • The Credential Chain
• 🔍 Additional Details
  • Resolution Order
  • Retry and GetTokenRetry Are Different Layers
  • Settings Are Honoured Per Credential
  • Legacy Flat Keys
• ⚙️ Configuration
  • Configuration in appsettings.json
  • Section Names
  • Shared Settings
  • Credential-Specific Settings
• 💡 Usage Examples
  • Raising the Azure CLI Timeout
  • Retrying Token Acquisition
  • Scoping to a Tenant
• 🔧 Troubleshooting
  • Azure CLI Authentication Timed Out
  • A Setting Appears to Be Ignored
• 📚 Reference
  • Classes
  • Default Values
• 💡 Best Practices

📋 Overview

Key Features

• Additive by design: every setting is nullable, so an unset value leaves the Azure SDK default in place
• Shared and per-credential layers: Common configures the whole chain, a named subsection overrides it for one credential
• Subprocess timeouts: ProcessTimeout for the Azure CLI credential, the setting that governs how long az may take
• Token-acquisition retries: GetTokenRetry retries GetToken itself, which the Azure Core retry options cannot do
• Authority host preserved: the host derived from the environment still applies, and can be overridden explicitly

The Credential Chain

Environment	Credentials, in order
Development	client secret, client certificate, Azure CLI, Visual Studio Code, Visual Studio
Other	client secret, client certificate, workload identity, client assertion, managed identity

Client secret and client certificate appear only when the corresponding flat keys are configured.

🔍 Additional Details

Resolution Order

For each credential the provider builds, settings are applied in four layers. A later layer overrides only the members it declares.

1. Azure SDK defaults, established by constructing the options object
2. The authority host derived from the environment name
3. Credential:Common
4. Credential:<CredentialName>

Because the derived authority host sits at layer 2, an explicit AuthorityHost in configuration wins, while a configuration that omits it keeps the derived value.

Retry and GetTokenRetry Are Different Layers

This distinction matters more than any other setting on the page.

Setting	What it retries	Recovers a CLI timeout
Retry	the credential’s own HTTP calls, to the Entra authority or IMDS	no
GetTokenRetry	the whole GetToken call, including the az subprocess	yes

Retry maps to Azure.Core.ClientOptions.Retry. It never sees a failure that happens before an HTTP request is issued, and a timed-out az process is exactly such a failure. GetTokenRetry wraps the credential instead, so it can retry anything the credential throws.

RetryPolicy is deliberately absent from the configuration surface: it takes a policy object with no bindable shape. Set it in code if you need it.

Settings Are Honoured Per Credential

TenantId and AdditionallyAllowedTenants are declared on each Azure Identity options type individually rather than on a shared base, and not every type declares them. A setting that the target options type does not expose is ignored rather than rejected.

TenantId, in particular, is ignored by the client secret, client certificate and client assertion credentials, which take the tenant as a constructor argument sourced from the flat TenantId key.

AdditionallyAllowedTenants replaces the existing list rather than appending to it, so the configured value is the complete set.

Legacy Flat Keys

Four flat keys predate the Credential section and still work. They apply to the Azure CLI credential only, and they are applied before the Credential section, so structured configuration wins where both are present.

Flat key	Equivalent
TenantId	Credential:AzureCli:TenantId
ProcessTimeout	Credential:AzureCli:ProcessTimeout
SubscriptionId	Credential:AzureCli:Subscription
AdditionallyAllowedTenants, semicolon-separated	Credential:AzureCli:AdditionallyAllowedTenants, an array

Prefer the Credential section in new configuration.

⚙️ Configuration

Configuration in appsettings.json

The Credential subsection is added to whatever section the caller already passes to Get.

{
  "MyStorage": {
    "TenantId": "00000000-0000-0000-0000-000000000000",

    "Credential": {
      "Common": {
        "AdditionallyAllowedTenants": [ "*" ],
        "Retry": {
          "MaxRetries": 3,
          "Delay": "00:00:01",
          "MaxDelay": "00:00:16",
          "Mode": "Exponential",
          "NetworkTimeout": "00:01:40"
        },
        "Diagnostics": {
          "IsLoggingEnabled": true,
          "IsAccountIdentifierLoggingEnabled": false
        }
      },

      "AzureCli": {
        "ProcessTimeout": "00:05:00",
        "GetTokenRetry": {
          "MaxAttempts": 3,
          "Delay": "00:00:02",
          "MaxDelay": "00:00:20",
          "Mode": "Exponential"
        }
      },

      "ClientCertificate": { "SendCertificateChain": true },
      "WorkloadIdentity": { "TokenFilePath": "/var/run/secrets/azure/tokens/azure-identity-token" },
      "ManagedIdentity": { "Retry": { "MaxRetries": 5 } }
    }
  }
}

Section Names

Subsection	Credential	Settings type
Common	all of the below	CredentialSettings
ClientSecret	ClientSecretCredential	CredentialSettings
ClientCertificate	ClientCertificateCredential	ClientCertificateCredentialSettings
AzureCli	AzureCliCredential	ProcessCredentialSettings
VisualStudioCode	VisualStudioCodeCredential	CredentialSettings
VisualStudio	VisualStudioCredential	CredentialSettings
WorkloadIdentity	WorkloadIdentityCredential	WorkloadIdentityCredentialSettings
ClientAssertion	ClientAssertionCredential	CredentialSettings
ManagedIdentity	ManagedIdentityCredential	CredentialSettings

Shared Settings

Available in Common and in every named subsection.

Property	Type	Description
AuthorityHost	uri	Overrides the authority host derived from the environment
TenantId	string	Default tenant, where the options type declares it
AdditionallyAllowedTenants	string array	Replaces the allowed-tenant list; * allows any
IsUnsafeSupportLoggingEnabled	bool	Enables ETW logging that may contain personal data
DisableInstanceDiscovery	bool	Skips Entra instance discovery, where the options type declares it
Retry	object	MaxRetries, Delay, MaxDelay, Mode, NetworkTimeout
Diagnostics	object	ApplicationId, IsLoggingEnabled, IsLoggingContentEnabled, IsTelemetryEnabled, IsDistributedTracingEnabled, IsAccountIdentifierLoggingEnabled, LoggedContentSizeLimit
GetTokenRetry	object	MaxAttempts, Delay, MaxDelay, Mode

Credential-Specific Settings

Subsection	Property	Type	Description
AzureCli	ProcessTimeout	timespan	How long the credential waits for az
AzureCli	Subscription	string	Subscription name or id, equivalent to az --subscription
ClientCertificate	SendCertificateChain	bool	Includes the x5c header for subject name / issuer authentication
WorkloadIdentity	ClientId	string	Client id of the service principal
WorkloadIdentity	TokenFilePath	string	Path to the federated token file

💡 Usage Examples

Raising the Azure CLI Timeout

Conditional access can push interactive token acquisition past the Azure SDK default, which surfaces as Azure CLI authentication timed out.

"Credential": {
  "AzureCli": { "ProcessTimeout": "00:05:00" }
}

Retrying Token Acquisition

A longer timeout helps a slow sign-in. A retry helps a transient one.

"Credential": {
  "AzureCli": {
    "ProcessTimeout": "00:05:00",
    "GetTokenRetry": { "MaxAttempts": 3, "Delay": "00:00:02", "Mode": "Exponential" }
  }
}

MaxAttempts counts the first attempt, so 3 means one attempt and two retries. A value of 1 or less disables the wrapper, and the credential is used unwrapped.

A credential that reports itself unavailable is never retried: that response is how it tells the chain to move to the next link, and retrying it would stall the chain.

Scoping to a Tenant

"Credential": {
  "Common": {
    "TenantId": "00000000-0000-0000-0000-000000000000",
    "AdditionallyAllowedTenants": [ "11111111-1111-1111-1111-111111111111" ]
  }
}

🔧 Troubleshooting

Azure CLI Authentication Timed Out

The credential launched az and gave up before it answered. Raise Credential:AzureCli:ProcessTimeout, but first confirm the CLI can produce a token at all:

az account get-access-token --resource https://storage.azure.com/ --tenant <tenant-id>

If that command hangs indefinitely, no timeout value will help. Repair or upgrade the Azure CLI and sign in again.

Note that a timed-out credential does not yield to the next link in the chain. A timeout is an authentication failure, not an unavailability, so ChainedTokenCredential surfaces it instead of falling through.

A Setting Appears to Be Ignored

Three causes account for nearly all cases.

• The target options type does not declare the property. TenantId on ClientSecret, for instance, is ignored because that credential takes its tenant as a constructor argument.
• A named subsection is overriding Common. The named value always wins.
• Retry was configured where GetTokenRetry was meant. See Retry and GetTokenRetry Are Different Layers.

📚 Reference

Classes

Class	Description
CredentialChainSettings	Root of the Credential subsection, with Common and one member per credential
CredentialSettings	Settings shared by every credential
ProcessCredentialSettings	Adds ProcessTimeout and Subscription
ClientCertificateCredentialSettings	Adds SendCertificateChain
WorkloadIdentityCredentialSettings	Adds ClientId and TokenFilePath
CredentialRetrySettings	Mirrors Azure.Core.RetryOptions
CredentialDiagnosticsSettings	Mirrors TokenCredentialDiagnosticsOptions
GetTokenRetrySettings	Retry policy applied around GetToken
CredentialSettingsApplier	Applies settings onto the Azure Identity options types
RetryingTokenCredential	Credential decorator implementing GetTokenRetry

Default Values

Setting	Default
GetTokenRetry:MaxAttempts	1, meaning no wrapper
GetTokenRetry:Delay	1 second
GetTokenRetry:MaxDelay	30 seconds
GetTokenRetry:Mode	Exponential

Every other default is the Azure SDK’s own, because an unset member is never written.

💡 Best Practices

• Put shared concerns in Common and reserve named subsections for genuine per-credential differences
• Reach for ProcessTimeout when sign-in is slow, and for GetTokenRetry when it is flaky; they solve different problems
• Keep GetTokenRetry:MaxAttempts small on the developer credentials, since each failed attempt can cost the full process timeout
• Leave IsUnsafeSupportLoggingEnabled off outside a deliberate diagnostic session, and never enable it in production
• Prefer the Credential section over the legacy flat keys, which cover the Azure CLI credential only